PATHMac OS 8 Developer Documentation > Human Interface Toolbox > Menu Manager >

Mac OS 8 Menu Manager Reference

DISCUSSION

When the Appearance Manager is available, your program should call the MenuEvent function instead of the MenuKey function. MenuEvent maps the keyboard equivalent character in the event structure to its corresponding menu and menu item. Unlike MenuKey , the MenuEvent function supports the Shift, Option, and Control modifier keys in addition to the Command key.

The MenuEvent function does not distinguish between uppercase and lowercase letters. This allows a user to invoke a keyboard equivalent command, such as the Copy command, by pressing the Command key and "c" or "C". For consistency between applications, you should define the keyboard equivalents of your commands so that they appear in uppercase in your menus.

If the given character maps to an enabled menu item in the current menu list, MenuEvent highlights the menu title of the chosen menu, returns the menu ID in the high-order word of its function result, and returns the chosen menu item in the low-order word of its function result. After performing the chosen task, your application should unhighlight the menu title using the HiliteMenu function.

You should not define menu items with identical keyboard equivalents. The MenuEvent function scans the menus from right to left and the items from top to bottom. If you have defined more than one menu item with identical keyboard equivalents, MenuEvent returns the first one it finds.

The MenuEvent function first searches the regular portion of the current menu list for a menu item with a keyboard equivalent matching the given key. If it doesn't find one there, it searches the submenu portion of the current menu list. If the given key maps to a menu item in a submenu, MenuEvent highlights the menu title in the menu bar that the user would normally pull down to begin traversing to the submenu. Your application should perform the desired command and then unhighlight the menu title.

You shouldn't assign a Command-Shift-number key sequence to a menu item as its keyboard equivalent; Command-Shift-number key sequences are reserved for use as 'FKEY' resources. Command-Shift-number key sequences are not returned to your application, but instead are processed by the Event Manager. The Event Manager invokes the 'FKEY' resource with a resource ID that corresponds to the number that activates it.

VERSION NOTES

Available with Appearance Manager 1.0 and later.

MenuKey

Maps a character key with the Command key to determine the keyboard equivalent of a menu item in a menu in the current menu list. When the Appearance Manager is available, call MenuEvent instead of MenuKey , in order to map the keyboard equivalent character in the event structure to its corresponding menu and menu item. Unlike MenuKey , the MenuEvent function supports the Shift, Option, and Control modifier keys in addition to the Command key.

VERSION NOTES

Not recommended with Appearance Manager 1.0 and later.

IsShowContextualMenuClick

Returns whether a particular event could invoke a contextual menu.

pascal Boolean IsShowContextualMenuClick(const EventRecord* inEvent);

inEvent

A pointer to the event structure that describes the event to examine.

function result

Returns a Boolean value indicating whether or not a contextual menu should be displayed. If true , the contextual menu should be displayed; if false , not.

DISCUSSION

Before calling the IsShowContextualMenuClick function, you should call InitContextualMenus . If no error is returned, you can then call IsShowContextualMenuClick .

Applications should call IsShowContextualMenuClick when they receive non-null events. If IsShowContextualMenuClick returns true , your application should generate its own menu and Apple Event descriptor ( AEDesc ), and then call ContextualMenuSelect to display and track the contextual menu, and then handle the user's choice.

If the mouse-down event did not invoke a contextual menu, then the application should check to see if the event occurred in the menu bar (using the FindWindow function) and, if so, call MenuSelect to allow the user to choose a command from the menu bar.

VERSION NOTES

Available with Appearance Manager 1.0 and later.

SEE ALSO

Contextual Menu Gestalt Selector Constants .

ContextualMenuSelect

Displays a contextual menu.

pascal OSStatus ContextualMenuSelect (
                     MenuHandle inMenu,
                     Point inGlobalLocation,
                     Boolean inReserved,
                     UInt32 inHelpType,
                     ConstStr255Param inHelpItemString,
                     const AEDesc* inSelection,
                     UInt32* outUserSelectionType,
                     SInt16* outMenuID,
                     UInt16* outMenuItem);

inMenu

Pass a handle to a menu containing application commands to display. The caller creates this menu based on the current context, the mouse location, and the current selection (if it was the target of the mouse). If you pass nil , only system commands will be displayed. The menu should be added to the menu list as a pop-up menu (using the InsertMenu function).

inGlobalLocation

Pass the location (in global coordinates) of the mouse near which the menu is to be displayed.

inReserved

Reserved for future use. Pass false for this parameter.

inHelpType

Pass an identifier specifying the type of help to be provided by the application; see Contextual Menu Help Type Constants .

inHelpItemString

Pass the string containing the text to be displayed for the help menu item. This string is unused unless you also pass the constant kCMOtherHelp in the inHelpType parameter.

inSelection

Pass a pointer to an object specifier for the current selection. This allows the system to examine the selection and add special system commands accordingly. Passing a value of nil indicates that no selection should be examined, and most likely, no special system actions will be included.

outUserSelectionType

Pass a pointer to an unsigned 32-bit value. On return, the value indicates what the user selected from the contextual menu; see Contextual Menu Help Type Constants .

outMenuID

Pass a pointer to a signed 16-bit value. On return, if outUserSelectionType is set to kCMMenuItemSelected , the value is set to the menu ID of the chosen item.

outMenuItem

Pass a pointer to an unsigned 16-bit value. On return, if outUserSelectionType is set to kCMMenuItemSelected , the value is set to the menu item chosen.

function result

A result code; see Result Codes . ContextualMenuSelect returns the result code userCanceledErr and sets outUserSelectionType to kCMNothingSelected to indicate that the user did not select anything from the contextual menu and no further processing is needed.

DISCUSSION

If the IsShowContextualMenuClick function returns true , you should call the ContextualMenuSelect function after generating your own menu and preparing an Apple Event descriptor ( AEDesc ) that describes the item for which your application is displaying a contextual menu. This descriptor may contain an object specifier or raw data and will be passed to all contextual menu plug-ins.

The system will add other items before displaying the contextual menu, and it will remove those items before returning, leaving the menu in its original state.

After all the system commands are added, the contextual menu is displayed and tracked. If the user selects one of the system items, it is handled by the system and the call returns as though the user didn't select anything from the menu. If the user selects any other item (or no item at all), the Menu Manager passes back appropriate values in the parameters outUserSelectionType , outMenuID , and outMenuItem .

Your application should provide visual feedback indicating the item that was clicked upon. For example, a click on an icon should highlight the icon, while a click on editable text should not eliminate the current selection.

If the outUserSelectionType parameter contains kCMMenuItemSelected , you should look at the outMenuID and outMenuItem parameters to determine what menu item the user chose and handle it appropriately. If the user selected kCMHelpItemSelected , you should open the proper Apple Guide sequence or other form of custom help.

VERSION NOTES

Available with Appearance Manager 1.0 and later.

SEE ALSO

Contextual Menu Gestalt Selector Constants .